
The MetaKit Library                 Version 1.4                 November, 1996
==============================================================================


DESCRIPTION

    The MetaKit Library is a software development library for data storage
    and easy manipulation of structured objects and collections in C++. 
    If you need bulky, powerful database functions look elsewhere, but if you
    need a small self-contained library to store structured data, read on.

    This software is distributed as shareware. Full source code is available.
    Please read the disclaimer, which is in the file "include\m4kit.h".  

    For the latest news about MetaKit, point your Internet browser to:
                            http://purl.net/meta4/metakit

    For an example of its use, check out the "CatFish" disk catalog browser.
    This freeware Windows utility demonstrates the size and speed of MetaKit.


FEATURES

    MAKE YOUR STRUCTURED DATA PERSISTENT
    + Data is loaded on-demand, with immediate access to any size data files.
    + Modifications are only made permanent when explicitly committed.

    GET THE ADVANTAGES OF A DATABASE IN C++
    + Any failure, even during commit, causes automatic rollback on next open.
    + Automatic file storage allocation, all repair/reclaim is automatic.

    TRANSPORT YOUR DATA ANYWHERE
    + All data can be flattened for streaming over a communications channel.
    + Files are portable across platforms: MS-DOS, Windows, Mac, and Unix.

    RUN-TIME DATA STRUCTURES
    + Data structures are dynamic, allowing you to write generic utilities.
    + Deal with file format changes and multiple formats as your code evolves. 

    HIGH PERFORMANCE
    + Can store millions of objects, instant access to any view/row/property.
    + Storage overhead for large collections of small objects can be very low.

    NO INCONVENIENT COMPROMISES
    + MetaKit does not depend on UI code, so it can be combined with any GUI.
    + Existing class libraries are used for string & container implementation.

    EASY TO READ, EASY TO USE
    + Only a few tiny header files, distracting details are well encapsulated.
    + Uses view / row / property classes with [] and () operator overloading.

    YOU STAY IN CONTROL
    + The code footprint of MetaKit is small, you can link it as LIB or DLL.
    + Complete, commented source code of MetaKit is available. No royalties.

    ONE SIZE FITS ALL
    + Small projects: simple headers, easy to work with, small code, any GUI.
    + Very large projects: complex structures, huge files, portable, failsafe.

    SOLID AND SUPPORTED
    + This design has evolved during many years of commercial C++ programming.
    + Your questions, comments, and suggestions will be taken very seriously.


GETTING STARTED

    To install this library and sample code, unpack the ZIP archive to a new
    directory (such as "C:\M4KIT"). Make sure to keep the original directory
    structure, with 'Use Directory Names' in WinZip or 'pkunzip -d' in MS-DOS.

    Please read the "WHATSNEW.TXT" file for the last-minute release details.

    The main introduction is in the file "M4KIT.HTM", which is in HTML format.
    The file "M4KITAPI.HLP" is the reference guide for this library (Winhelp).

    A simple disk-catalog program is included to illustrate many features.
    Emphasis is on data-manipulation, this example uses a rudimentary UI.
    The source code is in "examples\discat", the 16-bit Windows executable
    is called "bin\discat16.exe", the 32-bit version is "bin\discat.exe".

    Note:   You will need Microsoft's MFC250.DLL to run the 16-bit version, or
            the two files MFC42.DLL & MSVCRT.DLL to run the 32-bit version.
            If you do not have them, you may not be able to do much with the
            current MFC-only version of this software library, unfortunately.

    The "dump.exe" utility dumps the contents of datafiles, the "struct.exe"
    program shows their data structure, full source code for both is included.
    The "catsend.exe" and "catrecv.exe" sample applications demonstrate the
    exchange of MetaKit data over TCP/IP. The "ftpcat.exe" 32-bit console
    application creates catalog of remote FTP server directories (which are
    compatible with "discat" and "catfish").

    The CatFish disk catalog browser executable is available separately (see
    the MetaKit home page), the source and makefile for a DLL version of this
    program are included in this distribution.


ROADMAP

    Several header files and libraries have the digit four in their name to
    avoid potential name conflicts with other files on your system.


    DIRECTORIES

        The shareware distribution has the following directory structure:

            bin\        Executables of the examples
            examples\   Source code examples
            include\    Header files
            lib\        Libraries needed to build applications

        These directories contain everything you need to build applications
        for 32-bit and 16-bit Windows, as well as for MS-DOS (small-model).

        In addition, the source code version includes these directories:

            src\        C++ source files and private headers
            msvc152\    Microsoft Visual C++ 1.52 build areas
            msvc42\     Microsoft Visual C++ 4.2 build areas


    HEADER FILES

        The MetaKit library software is highly modular (loosely coupled).
        As a consequence, the headers you need to look at are quite small.
        The following headers are provided in the shareware version:

            include\m4kit.h     The single header you'll need to include.

        This is a wrapper for the following files:

            include\k4conf.h    Compatibility and common definitions
            include\k4view.h    Definition of views, cursors, and rows

        The remaining include files contain some less essential details:

            include\k4table.h   Persistent storage details (low-level)
            include\k4field.h   Structured field details (low-level)
            include\k4viewx.h   Additional view classes, used internally
            include\k4*.inl     Inline function definitions

        These files define all capabilities of the library, no more, no less.
        The core functionality is provided by the View and Storage classes.


    SOURCE CODE EXAMPLES

        These programs illustrate different aspects of the MetaKit library:

            examples\catfish    Source code of the freeware "CatFish" utility,
                                a tiny but very fast disk catalog browser.
                                Created with MSVC 1.52 as a Win16 application.
                                Does not require, but works fine with FTPCAT.

            examples\catrecv    Receives and displays disk catalog as a tree.
                                In MSVC 4.2, needs Win95 for the Tree control.
                                Requires catsend to feed it some information.

            examples\catsend    Sends catalog file over a TCP/IP connection.
                                Compiled with MSVC 4 (Win32), uses Winsock.
                                Requires a catalog file created with discat.

            examples\demo       Simple program illustrating basic concepts.
                                Will compile as MS-DOS and Win32 console app.

            examples\discat     A basic disk catalog, for Win16 and Win32.
                                Compiled as a small dialog-based application.
                                Shows use with a non-trivial data structure.

            examples\dump       A utility to dump the contents of a datafile.
                                Compiled as a (32-bit) console application.
                                Useful for debugging, various output formats.

            examples\ftpcat     Similar to discat, but this console app will
                                generate tree catalogs of remote ftp servers.
                                Its catalog files are compatible with catsend.
                                Requires MSVC 4, runs FTP.EXE for sessions.

            examples\myio       Demonstration of encrypted data file storage.
                                Will compile as MS-DOS and Win32 console app.

            examples\struct     This utility displays the data structure of a
                                datafile as a graph. It is distributed as an
                                MS-DOS large-model real-mode executable.

        The CATSEND/CATRECV programs work together to demonstrate streaming,
        generic file access (CATSEND knows nothing about the DISCAT format),
        and use without data files (CATRECV only captures and displays data).
        You need WINSOCK and TCP/IP, but you can run them on a single machine.
        The FTPCAT utility creates files compatible with CATSEND and CATRECV.
        Finally, CATFISH is a full-scale utility application, with source.


PORTABILITY

    This release has been tested with Microsoft Visual C++ 4.0-4.2 (Win 32),
    1.52 (Win 16 and MSDOS), Symantec C++ 7.2 (Win 32), and Watcom C++ 10.6
    (Win 32) and uses files/strings/containers of MFC (Microsoft Foundation
    Classes framework). The library can be linked statically or as DLL.

    Some newer C++ features such as templates and RTTI are not required for
    this release (exceptions are used, using MFC macros for 16-bit MSVC 1.52).
    The generic data types can be implemented surprisingly well without them,
    although templates (and STL) will be used once they are widely supported.

    All C++ identifiers with global scope include the digit four. Namespace
    support will be added when this addition to C++ becomes more widespread.

    Support for other compilers, frameworks, hardware platforms, and operating
    systems will be available in a "Universal version" (end November 1996).


REGISTRATION

    The MetaKit Library is not free, you must register for US$ 25 if you use
    this code in your own software after an evaluation period of 30 days. When
    used commercially, you must register and purchase the source code license
    for another US$ 65 to obtain the right to incorporate this library code.

    Payment of the US$ 25 registration fee entitles you to:

        * The right to use this software for personal and non-profit use
        * Download more Windows/MFC library versions, various C++ compilers
        * Timely notification by email of any new revisions and updates
        * Free registration of every revision for the coming 12 months
        * Quick response times for all technical support questions
        * A warm thank you - you're supporting me to continue this effort!

    For an additional US$ 65, you can purchase the MFC sources version:

        * The right to include and distribute object code for commercial use
        * Fully commented source code in C++ of the MetaKit library (MFC only)
        * Makefiles and test software for several Windows/MFC environments
        * A twelve month subscription to all major updates via email

    End November 1996, the Universal version will be available for $165:

        * All of the above, with sources and makefiles for multiple platforms
        * Datafiles are fully portable, streaming also works accross platforms
        * This version can be used on: MS-DOS, Windows, Macintosh, and Unix
        * Full access to all beta and final library builds in the support area
        * New ports will be announced and made available free of charge

    How to register your copy or purchase the MFC sources or UNIV version:

        INTERNET:       For registration using the world wide web, including
                        via a secure server on-line registration form, see:
                                http://mini.net/cgi-bin/sax?2020

        CREDIT CARD, CASH, CHECK, OR MONEY ORDERS:
                        You can use the enclosed REGISTER.EXE program to send
                        your order to the KAGI shareware registration service,
                        using email, fax, or regular mail.

        COMPUSERVE:     GO SWREG, select reg# 10351 (10352 for MFC sources),
                        and enter all details. Confirmation and any further
                        information will then be sent to you by email within
                        two business days.

        PHONE ORDERS:   You can call PsL at 800-2424-PsL or 713-524-6394 and
                        give them a MC, Visa, Amex, or Discover card number.
                        Specify item #14522 and which version you want.
                        To insure that you will receive the latest registered
                        version, PsL will notify us the day of your order and
                        additional information will be sent to you within two
                        business days.

        NOTE:   THE ABOVE PHONE NUMBERS ARE FOR CREDIT CARD, ETC. ORDERS ONLY.
                THE AUTHOR OF THIS LIBRARY CANNOT BE REACHED AT THESE NUMBERS.

        Any questions about the status of the shipment of the order, refunds,
        registration options, product details, tech support, volume discounts,
        site licenses, etc, must be directed to the email/fax addresses below.


DISTRIBUTION AND SUPPORT

    The MetaKit Library software package is copyright Meta Four Software, NL.
    You may not distribute this information, nor any portions thereof, as part
    of a general database- or object-persistence software library or utility.

    You may distribute this shareware release for any other purpose, provided
    that all files are included without change, including this description.

    Meta Four Software will provide technical support for 12 months, starting
    on the day your registration fee is received. If a problem with MetaKit is
    not resolved according to the specifications, you will be given the option
    to receive a refund of the purchase price.


CONTACT INFORMATION

    Jean-Claude Wippler          mailto:jcw@meta4.nl

    Meta Four Software             http://purl.net/meta4
    Meekrap oord 6
    3991 VE, Houten                 fax:+31 30 635 2337
    The Netherlands

    Member of the Association of Shareware Professionals (ASP).
